Summary

• Adds a 3rd "Limitations" bullet to docs/en/impersonation.md explaining that setIdentity() and clearIdentity() (and therefore logout()) silently end impersonation, with a recommended workaround for the common "refresh active user" use case.
• Adds a "Replacing the current identity" section to docs/en/authentication-component.md that documents setIdentity() (it wasn't documented in this file before) and links the impersonation warning.

Why

The interaction is real and surprising:

AuthenticationComponent::setIdentity() calls the service's clearIdentity() first, and AuthenticationService::clearIdentity() actively calls stopImpersonating() on any ImpersonationInterface authenticator that returns true for isImpersonating() (AuthenticationService.php#L194).

So an app pattern like

// AppController::beforeFilter()
if ($user && !$user->some_association) {
    $reloaded = $this->Users->get($user->id, finder: 'fullProfile');
    $this->Authentication->setIdentity($reloaded);
}

silently ends impersonation on every request where the association was missing. The recommended workaround (write to the request attribute directly) is small but isn't currently documented.

Notes

• Documentation only - no code changes.
• A separate draft PR (Add AuthenticationComponent::replaceIdentity() #788) proposes a replaceIdentity() convenience method that codifies the workaround as first-class API. This docs PR stands on its own and is useful regardless of whether Add AuthenticationComponent::replaceIdentity() #788 lands; the docs example just uses the manual withAttribute() form.